Mark Bukovich [MSFT]

Package Inspector for MSAL Android Native Guide

The Microsoft Authentication Library (MSAL) for Android Native contains a tool called Package Inspector. This tool presents a list of packages installed on an Android device and allows the user to view, copy, and paste the signature hash used to sign the application’s package. It can be very useful in troubleshooting and verifying the signature hash for applications installed on an Android device. Below is a guide on the installation, use, and common issues of the Package Inspector.

Some scenarios where the Package Inspector will be useful are:

  • You have successfully developed your application to use MSAL, but after deploying the app to the Google Play Store, the app fails to perform authentication. In this case, the Package Inspector will be useful to discover the new signature hash used by Google to sign the app package.
  • You are implementing MSAL in your Android application, but encounter the following error:
    “The redirect URI in the configuration file doesn’t match with the one generated with the package name and signature hash. Please verify the uri in the config file and your app registration in Azure portal.”
    In this case, you can use the Package Inspector to verify what the package signature hash is and correctly configure both the Azure Portal and application to use the correct signature hash.
  • You are implementing MSAL in your Android application, but encounter the following error:
    “Intent filter for: BrowserTabActivity is missing”
    This error can occur because the signature hash specified in the AndroidManifest.xml file does not match the signature hash actually used to sign the apk file. In this case, the Package Inspector will be useful to verify what the signature hash actually is.

Note: The best place to learn about MSAL for Android Native is the github page at the following link. The readme is a very good start.
https://github.com/AzureAD/microsoft-authentication-library-for-android

Prerequisites

You should have:

Installation

Option 1: Clone the repository directly into Android Studio

  1. Open Android Studio and close any open projects
  2. Click on “Get From Version Control”


  3. Make sure that “Git” is selected at the top of the window, paste in the repository url:
    https://github.com/AzureAD/microsoft-authentication-library-for-android.git
    and click “Clone



Option 2: Download as a zip file and open in Android Studio

  1. Download the repository at:
    https://github.com/AzureAD/microsoft-authentication-library-for-android/archive/refs/heads/dev.zip
  2. Extract the zip file to the directory of your choice.
  3. Open Android Studio and close any projects that are open.
  4. Click on “Open an Existing Project”


  5. Find and select the Root Package for the entire Android MSAL Repository; do not choose the ‘package-inspector’ directory (This small detail is important) and click “OK”. (I renamed the directory to ‘msal-android’, but it will be “microsoft-authentication-library-for-android-dev” by default)


Using the Package Inspector

  1. With the Android MSAL project open in Android Studio, connect the desired Android device. This can be a physical device connected to the computer’s USB port, or an emulator booted from Android Studio’s AVD manager. Make sure that your device appears in the drop-down list at the top of Android Studio and select it.
  2. To the left of the device drop-down, there is another drop-down list. Click this and select “package-inspector”


  3. Click the green “play” button (indicated in the screenshot above with a green circle all the way to the right) to build, install, and run the package inspector on the desired device.
  4. Look through the list of packages in the package-inspector app and click on a package for which you want to see the signature hash. All packages on the device that the package-inspector has permission to access will appear in this list.

Common Issues

Problems loading the tool into Android Studio:
It is very important to make sure that you are loading the root package from the MSAL repository and not individually the package inspector.

Make sure that the project you are loading into Android Studio is not package-inspector, but should be named this:
“microsoft-authentication-library-for-android-dev” or whatever you may have renamed the root repository on your system. See step 4 under Option 2 of the installation section of this blog post.

Not all packages appear in the Package Inspector:
This is a very likely issue to run into. You are able to install and open Package Inspector fine, and a list of packages appear in the app; however, you do not see packages for any of the apps you have installed on the device.

An explanation for the reason behind this can be found in Google’s documentation on a change that was introduced in Android 11 (API 30):
https://developer.android.com/training/package-visibility

How to fix it –
The way to fix the issue is to first open the AndroidManifest.xml file within the ‘package-inspector’ directory found on the left side of Android Studio.


And then add the following permission and query between the <manifest></manifest> tags:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.microsoft.inspector">

    ...

    <permission android:name="android.permission.QUERY_ALL_PACKAGES" />

    <queries>
        <intent>
            <action android:name="android.intent.action.MAIN" />
        </intent>
    </queries>

</manifest>

Rerun the application from Android Studio, and the changes will be installed. Now you should be able to see the packages you have installed.

Leave a Comment